<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>How to use Boost.Log in libraries?</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Log v2">
<link rel="up" href="../rationale.html" title="Rationale and FAQ">
<link rel="prev" href="msvc_link_fails_lnk1123.html" title="Why MSVC 2010 fails to link the library with error LNK1123: failure during conversion to COFF: file invalid or corrupt?">
<link rel="next" href="../reference.html" title="Reference">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="msvc_link_fails_lnk1123.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../rationale.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="log.rationale.how_to_use_in_libraries"></a><a class="link" href="how_to_use_in_libraries.html" title="How to use Boost.Log in libraries?">How to use Boost.Log
      in libraries?</a>
</h3></div></div></div>
<p>
        When using Boost.Log with libraries, there are several recommendadions to
        follow. First, as noted in the <a class="link" href="../installation/config.html" title="Configuring and building the library">library
        configuration</a> section, using the library in multiple modules (including
        libraries and the application itself) requires Boost.Log to be built as a
        shared library. This is needed because Boost.Log maintains a number of process-wide
        singletons and may not function correctly if these singletons are duplicated.
        If building Boost.Log as a shared library is not desirable, it is possible
        to encapsulate it in a single user's shared library and link the rest of
        the modules with that library. In this case, Boost.Log can be built as a
        shared library and linked into user's shared library. The shared library
        API and other modules must not use Boost.Log components, including:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            Logging core
          </li>
<li class="listitem">
            Sinks
          </li>
<li class="listitem">
            Loggers
          </li>
<li class="listitem">
            Attributes, including named scope markup
          </li>
<li class="listitem">
            Library configuration helpers, including filter, formatter and settings
            parsers
          </li>
</ul></div>
<p>
        However, user's shared library may provide its own API that will implement
        similar functionality, using relevant Boost.Log facilities internally.
      </p>
<p>
        Next, it is important to ensure that logging configuration is coordinated
        between all modules. For example, if a file log is needed, only one file
        sink must be added, regardless of how many libraries are using logging. The
        preferred way to achieve this is perform logging configuration only in the
        main application, for the following reasons:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            Logging configuration should be performed early in the <code class="computeroutput"><span class="identifier">main</span></code> function, which is implemented
            in the application. Using global constructors in libraries can be problematic
            due to undefined order of global initialization and the possibility of
            dynamic loading and unloading of the libraries.
          </li>
<li class="listitem">
            Libraries are normally "serving the needs" of the main application,
            and conceptually it is the application that must decide how the library
            exposes its diagnostic information such as logs. One application may
            want to output its logs to console, another one store it in a file, and
            a third one may want to completely suppress any logging. A well-behaving
            library should transparently support any such use case and Boost.Log
            allows to achieve exactly that.
          </li>
</ul></div>
<p>
        It should be noted that having logging configured by the application implies
        that the application is written in C++ and can use Boost.Log. If this is
        not the case, libraries should still allow for this design and offer an API
        for configuring logging on behalf of the application. Alternatively, a separate
        library written in C++ can be used for the sole purpose of configuring logging.
        This way logging set up decisions are still made by the application, indirectly
        through the library API.
      </p>
<p>
        To implement this design, here are recommendations for library writers:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            Libraries should refrain from adding or configuring sinks, filters or
            formatters, including using library configuration helpers. The exception
            is the aforementioned API that configures logging on behalf of the application,
            but this configuretion should not be performed by default.
          </li>
<li class="listitem">
            Libraries should be careful about adding or removing global and thread-specific
            attributes in the logging core - any such actions must be clearly documented.
          </li>
<li class="listitem">
            Libraries can freely create loggers, modify their attributes and emit
            log records.
          </li>
<li class="listitem">
            Libraries may use named scope markup, even if they don't register <a class="link" href="../detailed/attributes.html#log.detailed.attributes.named_scope" title="Named scopes"><code class="computeroutput"><span class="identifier">named_scope</span></code></a>
            attribute themselves. The application can add and configure this attribute,
            which will enable this information in the output.
          </li>
<li class="listitem">
            Libraries should document the attributes it uses, incliding their names
            and value types, so that the application can configure filters and formatters
            accordingly. This includes the message text attribute - in particular,
            it is important to know the type of the attribute value (e.g. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> vs. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span></code>)
            and what character encoding it uses. If possible, declare <a class="link" href="../detailed/expressions.html#log.detailed.expressions.attr_keywords" title="Defining attribute keywords">attribute
            keywords</a> for all attributes used by the library in a public header.
          </li>
<li class="listitem">
            Libraries are recommended to mark all log records they emit with an attribute.
            For example, all log records could be made in a specific <a class="link" href="../detailed/sources.html#log.detailed.sources.channel_logger" title="Loggers with channel support">channel</a>.
            This way the application will be able to configure logging specifically
            for the library (for example, extract log records from the library to
            a separate file or apply a different severity level threshold).
          </li>
</ul></div>
</div>
<div class="copyright-footer">Copyright © 2007-2024 Andrey Semashev<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>).
      </p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="msvc_link_fails_lnk1123.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../rationale.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
